[docs/manifest] Add Virtual Manifest section

Current documentation does not mention Virtual Manifests at all, which
can be confusing because they appear in error messages.

Here we add the definition, and provide a hint about `--all` option for
most cargo commands, which allow the command to work in the way most
probably expected.

Fixes <https://github.com/rust-lang/cargo/issues/3526>

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 25bdf388ffecab2516957f00141e987619ceedc6..49075ca359e052aa52d571ec60152f464046d932 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -48,9 +48,9 @@ This field specifies a URL to a website hosting the crate's documentation.
 If no URL is specified in the manifest file, [crates.io][cratesio] will
 automatically link your crate to the corresponding [docs.rs][docsrs] page.
 
-Documentation links from specific hosts are blacklisted. Hosts are added 
-to the blacklist if they are known to not be hosting documentation and are 
-possibly of malicious intent e.g. ad tracking networks. URLs from the 
+Documentation links from specific hosts are blacklisted. Hosts are added
+to the blacklist if they are known to not be hosting documentation and are
+possibly of malicious intent e.g. ad tracking networks. URLs from the
 following hosts are blacklisted:
 - rust-ci.org
 
@@ -485,6 +485,18 @@ and also be a member crate of another workspace (contain `package.workspace`).
 Most of the time workspaces will not need to be dealt with as `cargo new` and
 `cargo init` will handle workspace configuration automatically.
 
+## Virtual Manifest
+
+In workspace manifests, if the `package` table is present, the workspace root
+crate will be treated as a normal package, as well as a worksapce. If the
+`package` table is not present in a worksapce manifest, it is called a *virtual
+manifest*.
+
+When working with *virtual manifests*, package-related cargo commands, like
+`cargo build`, won't be available anymore. But, most of such commands support
+the `--all` option, will execute the command for all the non-virtual manifest in
+the workspace.
+
 # The project layout
 
 If your project is an executable, name the main source file `src/main.rs`. If it